chore: Install demo scripts to bin by EverWinter23 · Pull Request #85 · Arthur-Ficial/apfel

EverWinter23 · 2026-04-13T20:32:38Z

Summary

This change installs the demo scripts to bin dir via make.

The project was quite intriguing. I gave it a go. Unfortunately, the local model is not powerful enough to be useful.
However, it maybe possible that the next set of local models can come in handy in everyday workflows.

~/workspace/apfel >>> docker image ls                                               
REPOSITORY                       TAG           IMAGE ID       CREATED         SIZE
pgvector/pgvector                pg14          23c2907fbff1   8 months ago    627MB
mongo                            6.0           e6ea23317a13   8 months ago    1GB
redis                            6.2           37440b1f783e   9 months ago    179MB
timescale/timescaledb            latest-pg14   0f5553d37abb   11 months ago   1.68GB
prom/prometheus                  v2.53.4       502ad90314c7   13 months ago   369MB
temporalio/auto-setup            1.24.2        10e8c557ace5   21 months ago   546MB
temporalio/ui                    2.28.0        629b3e444f0b   21 months ago   126MB
rediscommander/redis-commander   latest        19cd0c49f418   4 years ago     133MB

~/workspace/apfel >>> cmd "how do i get all image ids in docker image ls command"                                                                                                                              
$ docker image ls | grep ID

~/workspace/apfel >>> cmd "how do i get the 3rd column of a command output"                                                                                                                                    
$ column -s 3 <output>

~/workspace/apfel >>> docker image ls | column -s 3                                                                                                                                                        
REPOSITORY                       TAG           IMAGE ID       CREATED         SIZE      timescale/timescaledb            latest-pg14   0f5553d37abb   11 months ago   1.68GB
scrollmark-api                   latest        4f41e1fb3f15   6 hours ago     6.6GB     prom/prometheus                  v2.53.4       502ad90314c7   13 months ago   369MB
pgvector/pgvector                pg14          23c2907fbff1   8 months ago    627MB     temporalio/auto-setup            1.24.2        10e8c557ace5   21 months ago   546MB
mongo                            6.0           e6ea23317a13   8 months ago    1GB       temporalio/ui                    2.28.0        629b3e444f0b   21 months ago   126MB
redis                            6.2           37440b1f783e   9 months ago    179MB     rediscommander/redis-commander   latest        19cd0c49f418   4 years ago     133MB

~/workspace/apfel >>> cmd "how do i get the 3rd column of a command output"                                                                                                                                    
$ `echo $1 | head -n 1 | awk '{print $3}'`

~/workspace/apfel >>> docker image ls | echo $1 | head -n 1 | awk '{print $3}'                                                                                                                             
# empty

~/workspace/apfel >>> docker image ls | awk '{print $3}'                                                                                                                                                   
IMAGE
4f41e1fb3f15
23c2907fbff1
e6ea23317a13
37440b1f783e
0f5553d37abb
502ad90314c7
10e8c557ace5
629b3e444f0b
19cd0c49f418                                                                                                                                                                            

~/workspace/apfel >>> explain "docker image ls | awk '{print $3}' "                                                                                                                                        
The command `docker image ls | awk '{print }'` is used to list all Docker images stored in a Docker registry
or local Docker container. The `docker image ls` command retrieves a list of all Docker images present in the
registry or the local Docker environment. The `awk` command is then used to filter out the output, which in
this case is simply printing the image names without any additional formatting.

This command will output a list of all Docker images, each on a new line, but since the `awk` command only
prints the output, it does not modify the output further, and you'll see the image names directly from the
Docker command's output.

Adds an "Install demos globally (optional)" section to demo/README.md with an apfel- prefixed symlink pattern that avoids PATH name collisions (port vs MacPorts, cmd vs common shell variable, etc.). Each demo script gets a one-line header pointing readers to that section. Demos stay intentionally out of `brew install apfel` / `make install`: names like `cmd`, `port`, `explain`, `naming` are too generic for global PATH, and users who want them available as commands can now follow the documented pattern. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Arthur-Ficial · 2026-04-14T20:19:43Z

Hey @EverWinter23 - thanks for the PR and for actually trying the demos on real workflows. That kind of dogfooding is genuinely useful feedback, even when it surfaces limitations.

After thinking it through, I've decided not to merge this as-is, but I've landed the intent behind it in a different shape. Here's the reasoning:

Why not auto-install to $PREFIX/bin

Name collisions. port would shadow MacPorts on any machine that has it installed. cmd, explain, naming are generic enough that they could collide with other tools or shell helpers silently.
Symlinks-to-$(pwd) are fragile. If a user git clones, runs make install-demo-scripts, then later moves or deletes the repo, they end up with dangling symlinks in their PATH forever.
Silent sudo. The if [ -w ... ]; then ln; else sudo ln branch would fire a sudo prompt mid-make with no warning. This was actually the exact pattern we just moved away from in make install doesn't handle non-existent binary dir #84 (v1.0.1), where make install now fails loudly with a clear error instead of silently escalating.
Demos are demos. They're intentionally small reference implementations, not shipped commands. The golden goal is three things - apfel as a UNIX tool, OpenAI-compatible server, and CLI chat - and the demos are examples of using those, not additional products.

What I did instead (commit ccf8e23 on main):

Added an "Install demos globally (optional)" section to demo/README.md documenting the opt-in symlink pattern with an apfel- prefix (so apfel-port 3000, apfel-cmd "..." - no collisions).
Added a one-line header to each of the 8 demo scripts pointing readers at that section.

The recommended pattern from the README:

mkdir -p "$HOME/.local/bin"
for d in cmd explain gitsum mac-narrator naming oneliner port wtd; do
  ln -sf "$(pwd)/demo/\$d" "\$HOME/.local/bin/apfel-\$d"
done

This gives users who want the demos globally the exact thing your PR was reaching for, without the collision + sudo + dangling-symlink risks of baking it into make.

Closing the PR but genuinely appreciated the nudge - the docs improvement wouldn't have happened without it. Feel free to open new PRs anytime.

chore: Install demo scripts to bin

3e9cc63

Arthur-Ficial closed this Apr 14, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

chore: Install demo scripts to bin#85

chore: Install demo scripts to bin#85
EverWinter23 wants to merge 1 commit intoArthur-Ficial:mainfrom
EverWinter23:EverWinter23/install-demo-scripts

EverWinter23 commented Apr 13, 2026

Uh oh!

Arthur-Ficial commented Apr 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

EverWinter23 commented Apr 13, 2026

Summary

Uh oh!

Arthur-Ficial commented Apr 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants